4 Input/Output

Since Eshell does not communicate with a terminal like most command shells, IO is a little different.

4.1 Visual Commands

If you try to run programs from within Eshell that are not line-oriented, such as programs that use ncurses, you will just get garbage output, since the Eshell buffer is not a terminal emulator. Eshell solves this problem by running such programs in Emacs’s terminal emulator.

Programs that need a terminal to display output properly are referred to in this manual as “visual commands,” because they are not simply line-oriented. You must tell Eshell which commands are visual, by adding them to eshell-visual-commands; for commands that are visual for only certain sub-commands – e.g., ‘git log’ but not ‘git status’ – use eshell-visual-subcommands; and for commands that are visual only when passed certain options, use eshell-visual-options.

Caution: Some tools such as Git use the pager ‘less’ by default to paginate their output but call it with its ‘-F’ option. This option causes ‘less’ to echo the output instead of paginating it if the output is less than one page long. This causes undesirable behavior if, e.g., ‘git diff’, is defined as a visual subcommand. It’ll work if the output is big enough and fail if it is less than one page long. If that occurs to you, search for configuration options for calling ‘less’ without the ‘-F’ option. For Git, you can do that using ‘git config --global core.pager 'less -+F'’.

If you want the buffers created by visual programs killed when the program exits, customize the variable eshell-destroy-buffer-when-process-dies to a non-nil value; the default is nil.

4.2 Redirection

Redirection is mostly the same in Eshell as it is in other command shells. The output redirection operators > and >> as well as pipes are supported, but there is not yet any support for input redirection. Output can also be redirected to buffers, using the >>> redirection operator, and Elisp functions, using virtual devices.

The buffer redirection operator, >>>, expects a buffer object on the right-hand side, into which it inserts the output of the left-hand side. e.g., ‘echo hello >>> #<buffer *scratch*>’ inserts the string "hello" into the *scratch* buffer. The convenience shorthand variant ‘#<buffer-name>’, as in ‘#<*scratch*>’, is also accepted.

eshell-virtual-targets is a list of mappings of virtual device names to functions. Eshell comes with two virtual devices: /dev/kill, which sends the text to the kill ring, and /dev/clip, which sends text to the clipboard.

You can, of course, define your own virtual targets. They are defined by adding a list of the form ‘("/dev/name" function mode)’ to eshell-virtual-targets. The first element is the device name; function may be either a lambda or a function name. If mode is nil, then the function is the output function; if it is non-nil, then the function is passed the redirection mode as a symbol–overwrite for >, append for >>, or insert for >>>–and the function is expected to return the output function.

The output function is called once on each line of output until nil is passed, indicating end of output.